<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.9.1"/>
<title>cocoOS: C:/Users/peter_000/Desktop/cocoOS/common/src/docMessages.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">cocoOS
   &#160;<span id="projectnumber">5.0.3</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.9.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li class="current"><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
  <div id="navrow2" class="tabs2">
    <ul class="tablist">
      <li><a href="files.html"><span>File&#160;List</span></a></li>
      <li><a href="globals.html"><span>Globals</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('doc_messages_8h.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">docMessages.h File Reference</div>  </div>
</div><!--header-->
<div class="contents">

<p><a href="doc_messages_8h_source.html">Go to the source code of this file.</a></p>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>If the tasks in an application needs to exchange more information than just simple events, they can use messages. The base type for messages is the Msg_t, which is a struct with three members: </p><div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>{</div>
<div class="line">    uint8_t signal;</div>
<div class="line">    uint8_t reserved;</div>
<div class="line">    uint16_t delay;</div>
<div class="line">} Msg_t;</div>
</div><!-- fragment --><p>The first member, <em>signal</em>, is used for message indentification by the application.<br />
<em>reserved</em> is an alignment byte.<br />
<em>delay</em> is used by the kernel when sending delayed messages. Should not be accessed by the application.</p>
<p>From this base type, the application can create its own message types containing the members needed: </p><div class="fragment"><div class="line"><span class="keyword">enum</span> {</div>
<div class="line">    LED_ON_SIG,</div>
<div class="line">    LED_OFF_SIG</div>
<div class="line">};</div>
<div class="line"></div>
<div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>{</div>
<div class="line">    Msg_t super;    <span class="comment">/* All application defined message types should inherit from the Msg_t */</span></div>
<div class="line">    uint8_t led;</div>
<div class="line">} LedMsg_t;</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">void</span> task( <span class="keywordtype">void</span> ) {</div>
<div class="line">    <span class="keyword">static</span> LedMsg_t ledMsg;</div>
<div class="line"></div>
<div class="line">    ledMsg.super.signal = LED_ON_SIG;</div>
<div class="line">    ledMsg.led = 0;</div>
<div class="line"></div>
<div class="line">    task_open();</div>
<div class="line">    ...</div>
<div class="line">    task_close();</div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Message passing</b> <br />
Messages are passed between tasks by copying the message into a message queue. The posted message must be of the same type that are held by the message queue. The application must allocate space for this message queue and pass the address of the queue, the queue length and the message size when creating the task: </p><div class="fragment"><div class="line"><span class="keyword">static</span> LedMsg_t msgpool[ Q_SIZE ];</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>) {</div>
<div class="line">    <a class="code" href="os__task_8c.html#af531a501491c2acab61a65c8741e1375">task_create</a>( task, prio, msgpool, Q_SIZE, <span class="keyword">sizeof</span>(LedMsg_t) );</div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Mutual exclusion and synchronization</b> <br />
For each message queue, cocoOS creates a binary semaphore and an event intended to be used for mutual exclusion and synchronization. <br />
 Before accessing the queue for either posting or receiving a message, the semaphore should is automatically acquired by the OS. If the semaphore is already taken by another task, the task will be put into the waiting state until the semaphore is released. <br />
 <br />
 The event associated with a message queue is automatically signaled when the queue contents changes, i.e. a message is posted to or removed from the queue. A task will be put to wait for the event when a message queue was full or empty when trying to post or receive a message respectively. Then when the event is signalled, the task makes a new post/receive retry to the message queue. <br />
When a message has been received or posted, the queue semaphore is finally automatically released by the OS. <br />
 <b>Posting messages</b> <br />
A message can be posted immediately into another task's message queue by using msg_post(). The message will be placed in the receiving task's message queue fifo and will be processed as soon as possible. With msg_post_in() it is possible to specify a delay before the message will be delivered to the receiving task. See also <b>Asynchronous message posting</b> below. </p><div class="fragment"><div class="line"><span class="keyword">static</span> Msg_t msgpool[ 16 ];</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)</div>
<div class="line">{</div>
<div class="line">    ...</div>
<div class="line">    <a class="code" href="os__task_8c.html#af531a501491c2acab61a65c8741e1375">task_create</a>( task1, 1, NULL, 0, 0 );</div>
<div class="line">    taskId2 = <a class="code" href="os__task_8c.html#af531a501491c2acab61a65c8741e1375">task_create</a>( task2, 2, msgpool, 16, <span class="keyword">sizeof</span>(Msg_t) );</div>
<div class="line">    <a class="code" href="os__task_8c.html#af531a501491c2acab61a65c8741e1375">task_create</a>( task3, 3, NULL, 0, 0 );</div>
<div class="line">    ...</div>
<div class="line">    <a class="code" href="os__kernel_8c.html#a19c7111cf2121a69331d99dabe3e9df0">os_start</a>();</div>
<div class="line">    <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"></div>
<div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> task1(<span class="keywordtype">void</span>) {</div>
<div class="line">    <span class="keyword">static</span> Msg_t msg;</div>
<div class="line"></div>
<div class="line">    msg.signal = 10MS_SIG;</div>
<div class="line">    </div>
<div class="line">    task_open();</div>
<div class="line">    </div>
<div class="line">    <span class="keywordflow">for</span> (;;) {</div>
<div class="line">        </div>
<div class="line">        task_wait( 10 );</div>
<div class="line">        </div>
<div class="line">        <span class="comment">/* Post the message into task2&#39;s queue */</span></div>
<div class="line">        msg_post( taskId2, msg) );</div>
<div class="line"></div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    task_close();</div>
<div class="line"></div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"></div>
<div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> task3(<span class="keywordtype">void</span>) {</div>
<div class="line">    <span class="keyword">static</span> Msg_t msg;</div>
<div class="line"></div>
<div class="line">    msg.signal = BUTTON_SIG;</div>
<div class="line">    </div>
<div class="line">    task_open();</div>
<div class="line">    </div>
<div class="line">    <span class="keywordflow">for</span> (;;) {</div>
<div class="line">        </div>
<div class="line">        event_wait( buttonEvt );</div>
<div class="line">        </div>
<div class="line">        <span class="comment">/* Post the message into task2&#39;s queue with 1000 ticks delay */</span></div>
<div class="line">        msg_post_in( taskId2, msg, 1000) );</div>
<div class="line"></div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    task_close();</div>
<div class="line"></div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Receiving messages</b><br />
Receiving messages is done in the same manner as posting messages, but using msg_receive() instead. See also <b>Asynchronous message receiving</b> below.<br />
<br />
</p><div class="fragment"><div class="line"><span class="keyword">static</span> Msg_t msgpool[ 16 ];</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)</div>
<div class="line">{</div>
<div class="line">    ...</div>
<div class="line">    <a class="code" href="os__task_8c.html#af531a501491c2acab61a65c8741e1375">task_create</a>( task1, 1, NULL, 0, 0 );</div>
<div class="line">    taskId2 = <a class="code" href="os__task_8c.html#af531a501491c2acab61a65c8741e1375">task_create</a>( task2, 2, msgpool, 16, <span class="keyword">sizeof</span>(Msg_t) );</div>
<div class="line">    ...</div>
<div class="line">    <a class="code" href="os__kernel_8c.html#a19c7111cf2121a69331d99dabe3e9df0">os_start</a>();</div>
<div class="line">    <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"></div>
<div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> task2(<span class="keywordtype">void</span>) {</div>
<div class="line">    <span class="keyword">static</span> Msg_t msg;</div>
<div class="line">    </div>
<div class="line">    task_open();</div>
<div class="line">    </div>
<div class="line">    <span class="keywordflow">for</span> (;;) {</div>
<div class="line">        </div>
<div class="line">        <span class="comment">/* Wait for a message */</span></div>
<div class="line">        msg_receive( taskId2, &amp;msg) );</div>
<div class="line"></div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    task_close();</div>
<div class="line"></div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Periodic messages</b><br />
A message can also be setup to be delivered periodically to its receiver with msg_post_every(). This message will be put into the message queue as a usual delayed message posted with the msg_post_in() method. When the message delay expires, the message is delivered to the task and reposted to the queue automatically with the timer reloaded. A posted periodic message can not be stopped, it will be delivered periodically forever. Note that this type of message should be posted outside the endless task loop. Otherwise the queue will quickly fill up and the system will be overloaded.</p>
<p><b>Asynchronous message posting</b><br />
The task can also post messages using the msg_post_async() function. The only difference from the usual msg_post() is that, the task will not block waiting for the queue if it was full. The task will continue executing immediately instead. <br />
</p>
<p><b>Asynchronous message receiving</b><br />
The msg_reveive_async() can be used to poll the queue for messages without blocking the task if the queue is empty. If there are no messages waiting in queue, the function will return immediately and the signal member of the msg parameter will be set to the value NO_MSG_ID (0xff)</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> ledTask( <span class="keywordtype">void</span> ) {</div>
<div class="line">    <span class="keyword">static</span> LedMsg_t msg;</div>
<div class="line"></div>
<div class="line">    task_open();</div>
<div class="line"></div>
<div class="line">    <span class="keywordflow">for</span> (;;) {</div>
<div class="line">        msg_receive_async( ledTaskId, &amp;msg );</div>
<div class="line"></div>
<div class="line">        <span class="keywordflow">if</span> ( msg.super.signal == LED_SIG ) {</div>
<div class="line">            blinkLed();</div>
<div class="line">        }</div>
<div class="line">        <span class="keywordflow">else</span> <span class="keywordflow">if</span> ( msg.super.signal == NO_MSG_ID ) {</div>
<div class="line">            <span class="comment">/* Do something else */</span></div>
<div class="line">        }</div>
<div class="line"></div>
<div class="line">        <span class="comment">/* Wait 200 ms before polling message queue again */</span></div>
<div class="line">        task_wait(200);</div>
<div class="line">    }</div>
<div class="line"></div>
<div class="line">    task_close();</div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Message API</b><br />
The message API consists of the following macros and functions:<br />
</p><ul>
<li>msg_post()</li>
<li>msg_post_async()</li>
<li>msg_post_in()</li>
<li>msg_receive()</li>
<li>msg_receive_async()</li>
<li>msg_post_every() </li>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="dir_bdd9a5d540de89e9fe90efdfc6973a4f.html">common</a></li><li class="navelem"><a class="el" href="dir_4e4d22e38ca4e2e8207825ee2d00bc54.html">src</a></li><li class="navelem"><a class="el" href="doc_messages_8h.html">docMessages.h</a></li>
    <li class="footer">Generated on Tue Aug 28 2018 17:58:05 for cocoOS by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.9.1 </li>
  </ul>
</div>
</body>
</html>
